@filigran/chatbot 3.20.0 → 3.22.0

package/CHANGELOG.md

@@ -8,7 +8,107 @@ the versions follow [semantic versioning](https://semver.org/spec/v2.0.0.html).
 This file starts at 3.10.0; earlier releases are on the
 [releases page](https://github.com/FiligranHQ/filigran-ui/releases).
 
-## 3.20.0 — unreleased
+## 3.22.0 — 2026-11-11
+
+### Added
+
+- `renderAgentIcon(name, { size })`: the host draws an agent icon given by
+  name (an icon library's, such as `brain-circuit`) in the conversation rows,
+  the agent switcher and its trigger; `null` keeps the panel's glyph. Image
+  URLs and emoji are still drawn by the panel.
+
+### Changed
+
+- A row's workspace marker keeps a readable minimum width and shows the whole
+  workspace name in the panel's tooltip when it is cut.
+- Error and warning states take the host's design-system tones: `theme.danger`
+  and `theme.warning` (`--filigran-chat-danger`, `--filigran-chat-warning`)
+  colour the notices, a failed upload, dictation and the stop button; unset, a
+  red and an amber per mode (red-700 and amber-800 in the light mode, which
+  read at 4.5:1 under a notice's wash). No Tailwind red or amber is left in the
+  notice or the composer.
+- A notice's close button shows the panel's tooltip instead of a native title,
+  with a 24 px hit area.
+- The agent switcher hands the focus back to its trigger on Escape and when an
+  agent is chosen, and the trigger is 32 px high like the other header controls.
+
+- Answers render their Markdown at the old chat page's quality and past it.
+  Fenced code is coloured by language (Python, TypeScript and JavaScript, JSON,
+  shell, SQL, YAML and their usual aliases) in light and dark, with no new
+  dependency; an unknown language stays plain. Tables read at the prose's size
+  with a filled header row, ruled and striped rows, cells that keep a readable
+  width and a frame that scrolls sideways when the table is wider than the
+  answer. Nested lists tighten and change bullet by level, task lists show
+  read-only boxes, h4 to h6, strikethrough and footnotes are styled.
+- Conversations come first in the list. The workspaces fold into one
+  "Workspaces" line above the conversations (with their count and the New
+  workspace button), opened on demand and remembered per browser
+  (`filigran-chat-workspaces-open`). Below it, every conversation is listed most
+  recent first, a filed one naming its workspace on its row. The "Not in a
+  workspace" heading becomes "Conversations"; dropping a row there still takes
+  it out of its workspace. Creating, opening, renaming and deleting a workspace,
+  filing a conversation, the default marker and the counts all work as before
+  inside the open line.
+
+### Changed
+
+- The new-conversation screen is short: the agent's mark, one greeting line
+  naming the agent, and the agent's own suggestions as compact chips. The
+  agent's description is no longer shown there (`ChatWelcome`'s
+  `agentDescription` is deprecated and ignored), the "Suggestions" heading is
+  gone, and the package's four generic fallback suggestions are removed: an
+  agent the suggestions route answers nothing for, with no host
+  `promptSuggestions`, shows no suggestion.
+- The header's agent control is one switcher: a click anywhere on the icon,
+  the name or the chevron opens a searchable list of the agents (always
+  searchable, ArrowUp / ArrowDown move, Enter switches, Escape closes, the
+  current agent checked). With `agentHref` or `onAgentNameClick`, the agent's
+  page moves to an "Open agent page" item of that menu, with the same rules
+  (in place, a modifier key left to the browser); the name is no longer a link.
+- Every error, warning and notice of the panel renders through one notice
+  block (`ChatNotice`): a tone (error, warning, info) with its icon, a tinted
+  container at the panel's radius, and a close button where the notice is not
+  tied to a live state. The composer's refused attachment and refused steer
+  or Stop notices close on a click; no notice is raw coloured text any more.
+  `useChat` returns `dismissNotice` and `dismissFileNotice`, and `ChatInput`
+  takes `onDismissNotice` and `onDismissFileNotice`.
+- While the agent thinks or acts, the composer's working glow plays whether the
+  field has the focus or not: the focus ring stands aside for the turn (the box
+  carries `data-working`) and comes back when the turn ends or is stopped. The
+  field keeps the focus after Enter, as before.
+
+### Added
+
+- A conversation row shows its agent's own icon (`agent_icon` of the list,
+  `ChatConversationSummary.agentIcon`: an image URL or an emoji, as
+  `XtmAgent.icon`) in place of the bot glyph, and its last line is the agent as
+  a small pill followed by the relative time, the time never cut. A backend
+  without `agent_icon`, or one the panel cannot draw, keeps the bot glyph.
+- `onConversationChange` says why the conversation changed: its second argument
+  is `{ created }`, true for a conversation the panel has just created from a
+  new chat (its first message or file), false for one opened from the list, on
+  a reload or in place of a deleted one, and when it is left for a new chat. A
+  host could not tell an opened conversation from a created one, as both came
+  after a new chat.
+- The composer takes the host's field tokens: `theme.inputRadius`,
+  `theme.inputMinHeight` and `theme.focusRing` set its corners, its height at
+  rest and its focus ring, so a host draws it with its design system and no
+  local override.
+- The conversation list of fullscreen and inline modes is resizable: drag its
+  right edge between 224 and 480 px, or move it with the arrow keys, Home and
+  End once focused; a double-click puts back the 256 px it always had. The
+  width is remembered per browser (`filigranChatConversationListWidth`,
+  namespaced by `storageKeyPrefix`) and kept while the list is collapsed.
+
+### Changed
+
+- The composer opens at two lines instead of one, and still grows with the
+  text up to its maximum: at one line it did not read as the place to write.
+- The composer's focus is a 2 px ring around its box instead of an accent
+  border, the text-field focus of a design system; the border keeps its colour,
+  so dictation's red border still reads.
+
+## 3.20.0 — 2026-11-10
 
 ### Added
 

package/README.md

@@ -80,6 +80,7 @@ import { ChatPanel } from '@filigran/chatbot';
 | `t`                 | `(key: string) => string`                 | —            | The host's translations; a key it returns unchanged falls back to the panel's catalog in `locale` (none without `locale`) — see [Internationalization](#internationalization) |
 | `accentColor`       | `string`                                  | `'#7b5cff'`  | Primary accent color (hex)                                       |
 | `logoIcon`          | `React.ReactNode`                         | default icon | Custom logo/icon for the assistant                               |
+| `renderAgentIcon`   | `(name: string, { size }) => ReactNode`   | —            | Draws an agent icon given by name (`brain-circuit`) in the conversation rows, the switcher and its trigger; `null` keeps the panel's glyph. Image URLs and emoji are drawn by the panel |
 | `promptSuggestions` | `string[]`                                | default list | Prompt suggestions shown on welcome screen                       |
 | `draftBorderColor`  | `string`                                  | —            | Color of the line above the composer (e.g. a draft context)      |
 | `draftLabel`        | `string`                                  | —            | Accepted, and not shown                                          |
@@ -105,7 +106,7 @@ import { ChatPanel } from '@filigran/chatbot';
 | `composerToolbar`   | `React.ReactNode`                         | —            | Extra controls appended to the composer toolbar. The escape hatch for host-specific affordances (XTM One's session-tool picker) — the package never learns what they are. Pass nothing and the toolbar simply has none. |
 | `storageKeyPrefix`  | `string`                                  | —            | Namespaces every key the panel keeps in browser storage (`<prefix>:filigranChatConversationId`, …), for a host mounting more than one panel |
 | `conversationId`    | `string \| null`                          | —            | The conversation on screen when the host owns it (a `?c=` URL); `null` is a new chat. Left `undefined`, the panel remembers its own, and a host-owned one is never written to storage |
-| `onConversationChange` | `(id: string \| null) => void`         | —            | Called whenever the conversation on screen changes, whoever changed it (a first answer, New chat, the history) |
+| `onConversationChange` | `(id: string \| null, change: { created: boolean }) => void` | —            | Called whenever the conversation on screen changes, whoever changed it (a first answer, New chat, the history); `created` is true for one the panel has just created from a new chat (its first message or file) |
 | `initialAgent`      | `string`                                  | —            | Agent selected once the list loads, by id or slug, over the remembered one |
 | `onAgentChange`     | `(agent: XtmAgent) => void`               | —            | Called when another agent is picked, in the menu or by opening a conversation of another agent: the picker follows the conversation on screen |
 | `readOnly`          | `boolean`                                 | `false`      | Hides the composer: a conversation the user may read but not write to |
@@ -146,8 +147,8 @@ import { ChatPanel } from '@filigran/chatbot';
 | `sidebarSearchThreshold` | `number`                             | `7`          | The conversation list's search box shows above this many conversations; `0` shows it from the first |
 | `channelLabel`      | `(channel: string) => string \| null \| undefined` | — | Names the channel a conversation was started in, on its row (`Started in {channel}`) and in the header (`Agent · {channel}`); `null` shows nothing, `undefined` keeps the panel's names (Slack, Teams, WhatsApp, Telegram, Discord, Google Chat) |
 | `headerTitle` / `headerSubtitle` | `React.ReactNode \| ((context: ChatHeaderContext) => React.ReactNode)` | — | A title beside the header's agent name and a line under it, or functions of the conversation on screen (as the list holds it) and the agent. Without `headerSubtitle`, the line reads `Agent · {channel}` for a conversation started in a channel its row names |
-| `agentHref`         | `(agent: XtmAgent) => string \| undefined` | —          | Links the header's agent name to this address (http(s) or a path of the host's origin), in place; the chevron beside it opens the picker |
-| `onAgentNameClick`  | `(agent: XtmAgent) => void`               | —            | Takes a plain click on the header's agent name (over `agentHref`); the chevron beside it opens the picker |
+| `agentHref`         | `(agent: XtmAgent) => string \| undefined` | —          | The agent's page (http(s) or a path of the host's origin), followed in place from the "Open agent page" item of the agent switcher; the header's agent control itself always opens the switcher |
+| `onAgentNameClick`  | `(agent: XtmAgent) => void`               | —            | Takes a plain click on the switcher's "Open agent page" item (over `agentHref`) |
 | `clearAllAction`    | `'delete' \| 'archive'`                   | `'delete'`   | What Clear all does, for its wording (`Archive all conversations`) |
 
 Plain-data props (`requestHeaders`, `apiEndpoints`, `pageContext`, `promptSuggestions`) are compared by content and callback props are called
@@ -1287,6 +1288,11 @@ both. The same variables may be set in CSS on an ancestor instead.
 | `surfaceSubtle`    | `--filigran-chat-surface-subtle`    | Cards, search boxes, a table's or a code block's header |
 | `surfaceHover`     | `--filigran-chat-surface-hover`     | A row or a button under the pointer |
 | `inputSurface`     | `--filigran-chat-input-surface`     | A text field: the composer (no fill unless set), a rename field, the feedback and approval comments |
+| `inputRadius`      | `--filigran-chat-input-radius`      | The composer's corners (0.75rem unset) |
+| `inputMinHeight`   | `--filigran-chat-input-min-height`  | The composer field's height at rest, before it grows with the text (two lines unset) |
+| `focusRing`        | `--filigran-chat-focus-ring`        | The 2 px ring around the composer while it has the focus (the accent unset) |
+| `danger`           | `--filigran-chat-danger`            | The tone of every error state: error notices, a failed upload, dictation, stop (a red unset, e.g. `var(--color-error)`) |
+| `warning`          | `--filigran-chat-warning`           | The tone of every warning notice (an amber unset, e.g. `var(--color-warning)`) |
 | `headerBackground` | `--filigran-chat-header-background` | The header's background, a colour or an image (`none` for the surface alone) |
 | `text`             | `--filigran-chat-text`              | Text |
 | `textMuted`        | `--filigran-chat-text-muted`        | Times, labels, hints and placeholders |
@@ -1440,11 +1446,14 @@ A host behind its own proxy points the routes at it, relative to its
 `{ prompts: '/prompts', quota: '/quota', feedback: '/conversations' }`
 (`feedback`: see [Message feedback](#message-feedback)).
 
-The welcome screen names the selected agent and shows its own suggestions —
-which is also how switching agent is confirmed: the thread resets to that
-screen, so without it nothing tells you who the next message will reach. When
-the suggestions route is unavailable the host's `promptSuggestions` prop is used
-instead, so the section is never empty.
+The welcome screen is short: the agent's mark, one greeting line naming the
+selected agent (which is also how switching agent is confirmed: the thread
+resets to that screen, so without it nothing tells you who the next message
+will reach), and the agent's own suggestions as compact chips. The agent's
+description is never shown there (it is picker and agent-page prose). When the
+suggestions route is unavailable the host's `promptSuggestions` prop is used
+instead; with neither, no suggestion is shown: the package carries no generic
+list of its own.
 
 Dictation needs no configuration at all: it uses the browser's own Web Speech
 API, so the mic button appears inside the text field, next to Send, wherever

package/dist/index.d.ts

@@ -392,6 +392,20 @@ interface ChatPanelTheme {
     surfaceHover?: string;
     /** A text field: the composer (no fill unless set), a rename field, the feedback and approval comments (`--filigran-chat-input-surface`). */
     inputSurface?: string;
+    /** The composer's corners, as the host's text fields draw theirs (`--filigran-chat-input-radius`, `radiusMd` unset). */
+    inputRadius?: string;
+    /** The small corner of every control, chip and avatar tile, the design system's `--radius-sm` (`--filigran-chat-radius-sm`, 4px unset). */
+    radiusSm?: string;
+    /** The card corner of every card, bubble, status indicator, menu and dialog, the design system's `--radius-md` (`--filigran-chat-radius-md`, 12px unset). */
+    radiusMd?: string;
+    /** The composer field's height at rest, before it grows with the text (`--filigran-chat-input-min-height`, two lines unset). */
+    inputMinHeight?: string;
+    /** The 2 px ring drawn around the composer while it has the focus (`--filigran-chat-focus-ring`, the accent unset). */
+    focusRing?: string;
+    /** The danger tone of every error state: notices, a failed upload, dictation, stop (`--filigran-chat-danger`, a red unset). */
+    danger?: string;
+    /** The warning tone of every warning notice (`--filigran-chat-warning`, an amber unset). */
+    warning?: string;
     /** The header's background, a colour or an image; `none` for the surface alone (`--filigran-chat-header-background`). */
     headerBackground?: string;
     /** Text (`--filigran-chat-text`). */
@@ -415,6 +429,10 @@ interface ChatPanelTheme {
     codeSize?: string;
     codeSurface?: string;
 }
+/** Draws an agent icon given by name at `size` pixels; `null` when the host has no such icon. */
+type ChatAgentIconRenderer = (name: string, options: {
+    size: number;
+}) => React.ReactNode;
 interface ChatPanelProps {
     mode: ChatPanelMode;
     /** Shows the close button; inline mode has none. */
@@ -449,6 +467,13 @@ interface ChatPanelProps {
     t?: Translate;
     accentColor?: string;
     logoIcon?: React.ReactNode;
+    /**
+     * Draws an agent icon given by name (`XtmAgent.icon`,
+     * `ChatConversationSummary.agentIcon`, e.g. `brain-circuit`), which the
+     * panel cannot draw itself: in the conversation rows and the agent switcher.
+     * `null` keeps the panel's glyph. Image URLs and emoji are drawn by the panel.
+     */
+    renderAgentIcon?: ChatAgentIconRenderer;
     promptSuggestions?: string[];
     /** Accepted, and not shown. */
     draftLabel?: string;
@@ -618,8 +643,14 @@ interface ChatPanelProps {
      * is a new chat. Left `undefined`, the panel remembers its own.
      */
     conversationId?: string | null;
-    /** Called whenever the conversation on screen changes, whoever changed it. */
-    onConversationChange?: (conversationId: string | null) => void;
+    /**
+     * Called whenever the conversation on screen changes, whoever changed it.
+     * `created` is true for a conversation the panel has just created from a new
+     * chat (its first message or file), false for one opened or left (the list, a
+     * reload, a new chat) and for one the backend put in place of a deleted one
+     * that was opened.
+     */
+    onConversationChange?: (conversationId: string | null, change: ChatConversationChange) => void;
     /** Agent selected once the list loads, by id or slug, over the remembered one. */
     initialAgent?: string;
     /**
@@ -954,6 +985,11 @@ interface ChatStreamEventInfo {
     /** The frame acknowledges a turn replayed from its start (`thinking` with `resumed`). */
     replayed?: boolean;
 }
+/** Why the conversation on screen changed (see `onConversationChange`). */
+interface ChatConversationChange {
+    /** The panel has just created this conversation from a new chat; false when it was opened, replaced or left. */
+    created: boolean;
+}
 /** What a host can do to a mounted panel, through its `ref`. */
 interface ChatPanelHandle {
     /** Send *text* as the user, leaving the composer's own draft alone; resolves to what became of it. */
@@ -1351,6 +1387,12 @@ interface ChatConversationSummary {
      * genuinely have no agent.
      */
     agentName?: string;
+    /**
+     * The conversation agent's icon (`agent_icon`), an image URL or an emoji as
+     * `XtmAgent.icon`, when the backend reports one: the row draws it in place of
+     * the panel's generic glyph.
+     */
+    agentIcon?: string;
     /**
      * The workspace the conversation is filed in (`null`: none), when the
      * backend reports it. Undefined on backends that do not.
@@ -1396,7 +1438,7 @@ interface XtmAgent {
     id: string;
     name: string;
     slug: string | null;
-    /** An image URL or an emoji; anything else shows the panel's logo. */
+    /** An image URL, an emoji, or a name drawn by `ChatPanelProps.renderAgentIcon`; else the panel's logo. */
     icon: string | null;
     description: string | null;
     /** The heading the agent picker lists it under; ungrouped agents come first. */
@@ -1429,4 +1471,4 @@ interface TransferredAgent {
 declare const voiceCallSupported: () => boolean;
 
 export { ChatPanel, ChatToggleButton, voiceCallSupported };
-export type { AgentStatusState, ApiEndpoints, BackendType, ChatAnsweredBy, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatCodeBlockContext, ChatCodeBlockRenderer, ChatContextBreakdown, ChatContextUsage, ChatConversationAction, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatFileRefusal, ChatHeaderContext, ChatHeldOutcome, ChatMarkerContext, ChatMarkerRenderer, ChatMessage, ChatMessagePersistedFeedback, ChatMessageSlotContext, ChatMode, ChatPanelHandle, ChatPanelMode, ChatPanelProps, ChatPanelTheme, ChatPromptTemplate, ChatQuotaStatus, ChatSendDecision, ChatSendDraft, ChatSendOptions, ChatSendOutcome, ChatSidebarSearch, ChatStreamEventInfo, ChatToggleButtonProps, ChatToolLabels, ChatTurnEnd, ChatTurnOutcome, ChatWorkspace, ConsultStatus, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };
+export type { AgentStatusState, ApiEndpoints, BackendType, ChatAgentIconRenderer, ChatAnsweredBy, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatCodeBlockContext, ChatCodeBlockRenderer, ChatContextBreakdown, ChatContextUsage, ChatConversationAction, ChatConversationChange, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatFileRefusal, ChatHeaderContext, ChatHeldOutcome, ChatMarkerContext, ChatMarkerRenderer, ChatMessage, ChatMessagePersistedFeedback, ChatMessageSlotContext, ChatMode, ChatPanelHandle, ChatPanelMode, ChatPanelProps, ChatPanelTheme, ChatPromptTemplate, ChatQuotaStatus, ChatSendDecision, ChatSendDraft, ChatSendOptions, ChatSendOutcome, ChatSidebarSearch, ChatStreamEventInfo, ChatToggleButtonProps, ChatToolLabels, ChatTurnEnd, ChatTurnOutcome, ChatWorkspace, ConsultStatus, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };